home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / idl / nsIXMLHttpRequest.idl < prev    next >
Text File  |  2006-05-08  |  14KB  |  358 lines
  1. /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is mozilla.org code.
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1998
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37.  
  38. #include "nsISupports.idl"
  39.  
  40. interface nsIDOMDocument;
  41. interface nsIDOMEventListener;
  42. interface nsIChannel;
  43. interface nsIVariant;
  44.  
  45. /**
  46.  * Mozilla's XMLHttpRequest is modelled after Microsoft's IXMLHttpRequest
  47.  * object. The goal has been to make Mozilla's version match Microsoft's
  48.  * version as closely as possible, but there are bound to be some differences.
  49.  *
  50.  * In general, Microsoft's documentation for IXMLHttpRequest can be used.
  51.  * Mozilla's interface definitions provide some additional documentation. The
  52.  * web page to look at is http://www.mozilla.org/xmlextras/
  53.  *
  54.  * Mozilla's XMLHttpRequest object can be created in JavaScript like this:
  55.  *   new XMLHttpRequest()
  56.  * compare to Internet Explorer:
  57.  *   new ActiveXObject("Msxml2.XMLHTTP")
  58.  *
  59.  * From JavaScript, the methods and properties visible in the XMLHttpRequest
  60.  * object are a combination of nsIXMLHttpRequest and nsIJSXMLHttpRequest;
  61.  * there is no need to differentiate between those interfaces.
  62.  *
  63.  * From native code, the way to set up onload and onerror handlers is a bit
  64.  * different. Here is a comment from Johnny Stenback <jst@netscape.com>:
  65.  *
  66.  *   The mozilla implementation of nsIXMLHttpRequest implements the interface
  67.  *   nsIDOMEventTarget and that's how you're supported to add event listeners.
  68.  *   Try something like this:
  69.  *
  70.  *   nsCOMPtr<nsIDOMEventTarget> target(do_QueryInterface(myxmlhttpreq));
  71.  *
  72.  *   target->AddEventListener(NS_LITERAL_STRING("load"), mylistener,
  73.  *                            PR_FALSE)
  74.  *
  75.  *   where mylistener is your event listener object that implements the
  76.  *   interface nsIDOMEventListener.
  77.  *
  78.  *   The 'onload' and 'onerror' attributes moved to nsIJSXMLHttRequest,
  79.  *   but if you're coding in C++ you should avoid using those.
  80.  */
  81. [scriptable, uuid(7b3b3c62-9d53-4abc-bc89-c33ce78f439f)]
  82. interface nsIXMLHttpRequest : nsISupports
  83. {
  84.   /**
  85.    * The request uses a channel in order to perform the
  86.    * request.  This attribute represents the channel used
  87.    * for the request.  NULL if the channel has not yet been
  88.    * created.
  89.    *
  90.    * In a multipart request case, this is the initial channel, not the
  91.    * different parts in the multipart request.
  92.    *
  93.    * Mozilla only. Requires elevated privileges to access.
  94.    */
  95.   readonly attribute nsIChannel channel;
  96.  
  97.   /**
  98.    * The response to the request is parsed as if it were a
  99.    * text/xml stream. This attributes represents the response as
  100.    * a DOM Document object. NULL if the request is unsuccessful or
  101.    * has not yet been sent.
  102.    */
  103.   readonly attribute nsIDOMDocument responseXML;
  104.  
  105.   /**
  106.    * The response to the request as text.
  107.    * NULL if the request is unsuccessful or
  108.    * has not yet been sent.
  109.    */
  110.   readonly attribute AString responseText;
  111.  
  112.  
  113.   /**
  114.    * The status of the response to the request for HTTP requests.
  115.    */
  116.   readonly attribute unsigned long status;
  117.  
  118.   /**
  119.    * The string representing the status of the response for
  120.    * HTTP requests.
  121.    */
  122.   readonly attribute AUTF8String statusText;
  123.  
  124.   /**
  125.    * If the request has been sent already, this method will
  126.    * abort the request.
  127.    */
  128.   void   abort();
  129.  
  130.   /**
  131.    * Returns all of the response headers as a string for HTTP
  132.    * requests.
  133.    *
  134.    * Note that this will return all the headers from the *current*
  135.    * part of a multipart request, not from the original channel.
  136.    *
  137.    * @returns A string containing all of the response headers.
  138.    *          NULL if the response has not yet been received.
  139.    */
  140.   string getAllResponseHeaders();
  141.  
  142.   /**
  143.    * Returns the text of the header with the specified name for
  144.    * HTTP requests.
  145.    *
  146.    * @param header The name of the header to retrieve
  147.    * @returns A string containing the text of the header specified.
  148.    *          NULL if the response has not yet been received or the
  149.    *          header does not exist in the response.
  150.    */
  151.   ACString getResponseHeader(in AUTF8String header);
  152.  
  153.   /**
  154.    * Native (non-script) method to initialize a request. Note that
  155.    * the request is not sent until the <code>send</code> method
  156.    * is invoked.
  157.    *
  158.    * Will abort currently active loads.
  159.    *
  160.    * After the initial response, all event listeners will be cleared.
  161.    * Call open() before setting new event listeners.
  162.    *
  163.    * @param method The HTTP method, for example "POST" or "GET". Ignored
  164.    *               if the URL is not a HTTP(S) URL.
  165.    * @param url The URL to which to send the request.
  166.    * @param async Whether the request is synchronous or asynchronous
  167.    *              i.e. whether send returns only after the response
  168.    *              is received or if it returns immediately after
  169.    *              sending the request. In the latter case, notification
  170.    *              of completion is sent through the event listeners.
  171.    *              This argument must be true if the multipart
  172.    *              attribute has been set to true, or an exception will
  173.    *              be thrown.
  174.    * @param user A username for authentication if necessary.
  175.    * @param password A password for authentication if necessary.
  176.    */
  177.   [noscript] void   openRequest(in AUTF8String method,
  178.                                 in AUTF8String url,
  179.                                 in boolean async,
  180.                                 in AString user,
  181.                                 in AString password);
  182.  
  183.   /**
  184.    * Meant to be a script-only method for initializing a request.
  185.    * The parameters are similar to the ones detailed in the
  186.    * description of <code>openRequest</code>, but the last
  187.    * 3 are optional.
  188.    *
  189.    * Will abort currently active loads.
  190.    *
  191.    * After the initial response, all event listeners will be cleared.
  192.    * Call open() before setting new event listeners.
  193.    *
  194.    * @param method The HTTP method - either "POST" or "GET". Ignored
  195.    *               if the URL is not a HTTP URL.
  196.    * @param url The URL to which to send the request.
  197.    * @param async (optional) Whether the request is synchronous or
  198.    *              asynchronous i.e. whether send returns only after
  199.    *              the response is received or if it returns immediately after
  200.    *              sending the request. In the latter case, notification
  201.    *              of completion is sent through the event listeners.
  202.    *              The default value is true.
  203.    *              This argument must be true if the multipart
  204.    *              attribute has been set to true, or an exception will
  205.    *              be thrown.
  206.    * @param user (optional) A username for authentication if necessary.
  207.    *             The default value is the empty string
  208.    * @param password (optional) A password for authentication if necessary.
  209.    *                 The default value is the empty string
  210.    */
  211.   void   open(in AUTF8String method, in AUTF8String url);
  212.  
  213.   /**
  214.    * Sends the request. If the request is asynchronous, returns
  215.    * immediately after sending the request. If it is synchronous
  216.    * returns only after the response has been received.
  217.    *
  218.    * After the initial response, all event listeners will be cleared.
  219.    * Call open() before setting new event listeners.
  220.    *
  221.    * @param body Either an instance of nsIDOMDocument, nsIInputStream
  222.    *             or a string (nsISupportsString in the native calling
  223.    *             case). This is used to populate the body of the
  224.    *             HTTP request if the HTTP request method is "POST".
  225.    *             If the parameter is a nsIDOMDocument, it is serialized.
  226.    *             If the parameter is a nsIInputStream, then it must be
  227.    *             compatible with nsIUploadChannel.setUploadStream, and a
  228.    *             Content-Length header will be added to the HTTP request
  229.    *             with a value given by nsIInputStream.available.  Any
  230.    *             headers included at the top of the stream will be
  231.    *             treated as part of the message body.  The MIME type of
  232.    *             the stream should be specified by setting the Content-
  233.    *             Type header via the setRequestHeader method before
  234.    *             calling send.
  235.    */
  236.   void   send(in nsIVariant body);
  237.  
  238.   /**
  239.    * Sets a HTTP request header for HTTP requests. You must call open
  240.    * before setting the request headers.
  241.    *
  242.    * @param header The name of the header to set in the request.
  243.    * @param value The body of the header.
  244.    */
  245.   void   setRequestHeader(in AUTF8String header, in AUTF8String value);
  246.  
  247.   /**
  248.    * The state of the request.
  249.    *
  250.    * Possible values:
  251.    *   0 UNINITIALIZED open() has not been called yet.
  252.    *   1 LOADING       send() has not been called yet.
  253.    *   2 LOADED        send() has been called, headers and status are available.
  254.    *   3 INTERACTIVE   Downloading, responseText holds the partial data.
  255.    *   4 COMPLETED     Finished with all operations.
  256.    */
  257.   readonly attribute long readyState;
  258.  
  259.   /**
  260.    * Override the mime type returned by the server (if any). This may
  261.    * be used, for example, to force a stream to be treated and parsed
  262.    * as text/xml, even if the server does not report it as such. This
  263.    * must be done before the <code>send</code> method is invoked.
  264.    *
  265.    * @param mimetype The type used to override that returned by the server
  266.    *                 (if any).
  267.    */
  268.   void   overrideMimeType(in AUTF8String mimetype);
  269.  
  270.   /**
  271.    * Set to true if the response is expected to be a stream of
  272.    * possibly multiple (XML) documents. If set to true, the content
  273.    * type of the initial response must be multipart/x-mixed-replace or
  274.    * an error will be triggerd. All requests must be asynchronous.
  275.    *
  276.    * This enables server push. For each XML document that's written to
  277.    * this request, a new XML DOM document is created and the onload
  278.    * handler is called inbetween documents. Note that when this is
  279.    * set, the onload handler and other event handlers are not reset
  280.    * after the first XML document is loaded, and the onload handler
  281.    * will be called as each part of the response is received.
  282.    */
  283.   attribute boolean multipart;
  284. };
  285.  
  286.  
  287. [scriptable, function, uuid(6459B7CE-6B57-4934-A0AF-0133BA6F9085)]
  288. interface nsIOnReadyStateChangeHandler : nsISupports {
  289.   /**
  290.    * Helper to implement the onreadystatechange callback member.
  291.    * You should not need to use this.
  292.    */
  293.   void handleEvent();
  294. };
  295.  
  296. [scriptable, uuid(9deabc90-28d5-41d3-a660-474f2254f4ba)]
  297. interface nsIJSXMLHttpRequest : nsISupports {
  298.   /**
  299.    * Meant to be a script-only mechanism for setting a load event listener.
  300.    * The attribute is expected to be JavaScript function object. When
  301.    * the load event occurs, the function is invoked.
  302.    * This attribute should not be used from native code!!
  303.    *
  304.    * After the initial response, all event listeners will be cleared.
  305.    * Call open() before setting new event listeners.
  306.    *
  307.    * Mozilla only.
  308.    */
  309.   attribute nsIDOMEventListener onload;
  310.  
  311.   /**
  312.    * Meant to be a script-only mechanism for setting an error event listener.
  313.    * The attribute is expected to be JavaScript function object. When
  314.    * the error event occurs, the function is invoked.
  315.    * This attribute should not be used from native code!!
  316.    *
  317.    * After the initial response, all event listeners will be cleared.
  318.    * Call open() before setting new event listeners.
  319.    *
  320.    * Mozilla only.
  321.    */
  322.   attribute nsIDOMEventListener onerror;
  323.  
  324.   /**
  325.    * Meant to be a script-only mechanism for setting a progress event listener.
  326.    * The attribute is expected to be JavaScript function object. When
  327.    * the error event occurs, the function is invoked.
  328.    * This attribute should not be used from native code!!
  329.    * This event listener may be called multiple times during the open request.
  330.    *
  331.    * After the initial response, all event listeners will be cleared.
  332.    * Call open() before setting new event listeners.
  333.    *
  334.    * Mozilla only.
  335.    */
  336.   attribute nsIDOMEventListener onprogress;
  337.  
  338.   /**
  339.    * Meant to be a script-only mechanism for setting a callback function.
  340.    * The attribute is expected to be JavaScript function object. When the
  341.    * readyState changes, the callback function will be called.
  342.    * This attribute should not be used from native code!!
  343.    *
  344.    * After the initial response, all event listeners will be cleared.
  345.    * Call open() before setting new event listeners.
  346.    */
  347.   attribute nsIOnReadyStateChangeHandler onreadystatechange;
  348. };
  349.  
  350. %{ C++
  351. #define NS_XMLHTTPREQUEST_CID                       \
  352.  { /* d164e770-4157-11d4-9a42-000064657374 */       \
  353.   0xd164e770, 0x4157, 0x11d4,                       \
  354.  {0x9a, 0x42, 0x00, 0x00, 0x64, 0x65, 0x73, 0x74} }
  355. #define NS_XMLHTTPREQUEST_CONTRACTID \
  356. "@mozilla.org/xmlextras/xmlhttprequest;1"
  357. %}
  358.